Hermes Agent 部署配置使用完全实战指南
前言
Hermes 是 Nous Research 开源的 AI Agent 项目,分两个部分:
- hermes-agent — 核心 Agent 引擎,CLI 交互 + 网关服务,支持接入飞书、Telegram、Slack 等消息平台
- hermes-desktop — Electron 桌面客户端,提供 GUI 交互界面
这篇文档记录的是在 macOS 上从零部署到跑通飞书机器人的完整过程。不讲原理,只讲操作。拿着这篇文档,你可以在一台干净的 Mac 上 30 分钟内完成全部部署。
环境信息:
| 项目 | 版本 |
|---|---|
| macOS | Sonoma (Darwin 24.6.0, x86_64) |
| hermes-agent | v0.14.0 |
| hermes-desktop | v0.4.5 |
| Homebrew | 5.x |
1. 前置依赖
hermes-agent 的安装脚本会自动检测并安装大部分依赖,但有一个硬性前提:Homebrew 必须提前装好。
1.1 安装 Homebrew(如果没有)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
安装完成后确认:
brew --version
# Homebrew 5.x.x
1.2 安装脚本会自动处理的依赖
以下依赖不需要手动安装,hermes 安装脚本会自动搞定:
| 依赖 | 用途 | 安装方式 |
|---|---|---|
| uv | Python 包管理器 | 自动安装到 ~/.local/bin |
| Python 3.11 | Agent 运行时 | 通过 uv 安装 |
| Node.js 22 LTS | 浏览器工具 | 安装到 ~/.hermes/node/ |
| ripgrep | 文件搜索 | 通过 Homebrew 安装 |
| Playwright Chromium | 浏览器引擎 | 自动下载 |
1.3 hermes-desktop 额外需要的依赖
构建 desktop 版本时会用到 gettext 库(DMG 打包依赖),需要提前安装:
brew install gettext
不装这个,构建到最后一步打 DMG 包时会报
Library not loaded: /usr/local/opt/gettext/lib/libintl.8.dylib错误。
2. 安装 hermes-agent
2.1 一键安装
一条命令搞定:
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
安装过程大约 5-10 分钟(取决于网络),你会看到逐项检测和安装的输出。全部绿色 ✓ 就是成功。
2.2 安装完成后的目录结构
~/.hermes/
├── hermes-agent/ # Agent 源码和 venv
├── node/ # Node.js 运行时
├── config.yaml # 主配置文件(模型、终端、网关等)
├── .env # 环境变量(API Key、消息平台凭证等)
├── SOUL.md # Agent 人格设定(可自定义)
├── skills/ # 内置技能(90+ 个)
├── sessions/ # 会话存储
├── logs/ # 日志
└── cron/ # 定时任务
2.3 激活命令
安装脚本会自动把 ~/.local/bin 加入 PATH,但当前 shell 需要手动刷新:
source ~/.zshrc
验证安装:
hermes --help
3. 安装 hermes-desktop
3.1 克隆并安装依赖
cd /tmp
git clone https://github.com/fathah/hermes-desktop.git
cd hermes-desktop
确保 Node.js 在 PATH 中(hermes-agent 安装的 Node.js):
export PATH="$HOME/.hermes/node/bin:$PATH"
npm install
npm install 大约需要 10 分钟,会下载 900+ 个包并编译 better-sqlite3 原生模块。有几个 deprecated 警告可以忽略。
3.2 构建 macOS 版本
npm run build:mac
构建产物在 dist/ 目录下:
dist/
├── mac/
│ └── Hermes Agent.app # macOS 应用
├── hermes-desktop-0.4.5-x64-mac.zip
└── hermes-desktop-0.4.5-x64.dmg
3.3 安装到 Applications
cp -R 'dist/mac/Hermes Agent.app' /Applications/
注意: 由于没有 Apple 开发者证书签名,首次打开时 macOS 会弹出安全警告。解决方法:系统设置 → 隐私与安全性 → 安全性,找到被阻止的应用,点击"仍要打开"。
4. 配置自定义模型网关
hermes 默认走 OpenRouter,但支持接入任何 OpenAI 兼容的 API 网关。这里以自建网关为例。
4.1 修改 config.yaml
编辑 ~/.hermes/config.yaml,找到 model: 部分,修改三个关键字段:
model:
default: "gpt-5.5" # 你要用的模型名
provider: "custom" # 使用自定义端点
base_url: "https://your-gateway.example.com/v1" # 你的网关地址
api_key: "sk-your-api-key-here" # 你的 API Key
同时在 ~/.hermes/.env 中也设置 OPENAI_API_KEY(部分组件会读这个环境变量):
OPENAI_API_KEY=sk-your-api-key-here
4.2 验证模型连通性
hermes
启动 CLI 后输入一句话测试,能正常回复就说明网关配置没问题。
5. 配置飞书机器人
hermes 原生支持飞书(Feishu/Lark),通过 WebSocket 长连接模式工作,不需要公网回调地址。
5.1 创建飞书应用
- 打开 飞书开放平台
- 创建一个自建应用
- 记录 App ID 和 App Secret
5.2 配置应用权限
在飞书开放平台的应用管理页面,添加以下权限:
| 权限 | 说明 |
|---|---|
im:message | 接收消息 |
im:message:send_as_bot | 以机器人身份发送消息 |
im:chat:readonly | 读取群聊信息 |
添加完权限后,创建版本并发布(审核通过后才生效)。
5.3 开启长连接模式
在飞书开放平台的应用管理页面:事件与回调 → 选择 WebSocket 模式。
这一步很关键,不开启的话 hermes 的 websocket 连接模式用不了。
5.4 写入环境变量
编辑 ~/.hermes/.env,追加以下内容:
# =============================================================================
# FEISHU / LARK INTEGRATION
# =============================================================================
FEISHU_APP_ID=cli_xxxxxxxxxxxx # 替换为你的 App ID
FEISHU_APP_SECRET=xxxxxxxxxxxxxxxxxx # 替换为你的 App Secret
FEISHU_DOMAIN=feishu # 国内用 feishu,国际版用 lark
FEISHU_CONNECTION_MODE=websocket # WebSocket 模式,无需公网 IP
# 允许所有用户访问(测试阶段)
GATEWAY_ALLOW_ALL_USERS=true
安全提示: 生产环境不建议
GATEWAY_ALLOW_ALL_USERS=true,应该用FEISHU_ALLOWED_USERS=user_id_1,user_id_2做白名单控制。
6. 启动网关服务
6.1 安装为系统服务(推荐)
hermes gateway install
这会创建一个 macOS launchd 服务(ai.hermes.gateway),开机自启,后台常驻。
服务文件位置:~/Library/LaunchAgents/ai.hermes.gateway.plist
6.2 常用管理命令
# 查看状态
hermes gateway status
# 重启服务
hermes gateway restart
# 查看日志(实时)
tail -f ~/.hermes/logs/gateway.log
# 查看错误日志
tail -f ~/.hermes/logs/gateway.error.log
# 卸载服务
hermes gateway uninstall
6.3 验证飞书连接
启动后检查日志,看到以下内容就说明飞书连接成功:
INFO gateway.platforms.feishu: [Feishu] Connected in websocket mode (feishu)
INFO gateway.run: ✓ feishu connected
[Lark] connected to wss://msg-frontier.feishu.cn/ws/v2?...
7. 首次使用:配对与频道设置
7.1 用户配对
第一次在飞书给机器人发消息时,会收到配对验证提示:
Hi~ I don't recognize you yet!
Here's your pairing code: XXXXXXXX
Ask the bot owner to run:
hermes pairing approve feishu XXXXXXXX
在 Mac 上执行批准命令:
hermes pairing approve feishu XXXXXXXX
批准后再发消息就能正常对话了。
7.2 设置主频道
配对成功后会收到设置主频道的提示。在飞书对话中回复:
/sethome
主频道用于接收定时任务结果和跨平台通知。
8. 其他常用操作
8.1 CLI 模式直接对话
不需要飞书,直接在终端对话:
hermes
8.2 修改 Agent 人格
编辑 ~/.hermes/SOUL.md,自定义 Agent 的人格、语气和行为偏好。
8.3 配置向导
首次使用建议跑一遍配置向导:
hermes setup
8.4 更新版本
hermes update
8.5 查看/编辑配置
hermes config # 查看当前配置
hermes config edit # 用编辑器打开配置文件
9. 踩坑记录
9.1 hermes-desktop 构建报 libintl.8.dylib 找不到
现象:
dyld: Library not loaded: /usr/local/opt/gettext/lib/libintl.8.dylib
原因: electron-builder 的 DMG 打包工具依赖 gettext 库。
解决:
brew install gettext
然后重新 npm run build:mac。
9.2 飞书权限不足导致获取群聊信息失败
现象: 日志中出现:
Access denied. One of the following scopes is required: [im:chat:readonly, im:chat, im:chat:read]
解决: 去飞书开放平台给应用添加 im:chat:readonly 权限,发布新版本。
9.3 所有用户被拒绝
现象: 日志中出现:
No user allowlists configured. All unauthorized users will be denied.
解决: 在 ~/.hermes/.env 中添加:
GATEWAY_ALLOW_ALL_USERS=true
或者配置白名单:
FEISHU_ALLOWED_USERS=ou_xxxxxxxxxxxx
修改后执行 hermes gateway restart 重启生效。
9.4 Git clone hermes-agent 仓库很慢
现象: 安装脚本卡在 Cloning into '/Users/xxx/.hermes/hermes-agent'... 很久。
解决: hermes-agent 仓库较大,国内网络环境可能较慢。可以考虑:
- 挂代理
- 或者手动用镜像站 clone 到
~/.hermes/hermes-agent,再跑安装脚本
10. 文件速查表
| 文件 | 用途 |
|---|---|
~/.hermes/config.yaml | 主配置:模型、终端、网关 |
~/.hermes/.env | 环境变量:API Key、平台凭证 |
~/.hermes/SOUL.md | Agent 人格设定 |
~/.hermes/skills/ | 技能目录(90+ 内置技能) |
~/.hermes/logs/gateway.log | 网关日志 |
~/.hermes/logs/gateway.error.log | 网关错误日志 |
~/.hermes/sessions/ | 会话持久化存储 |
~/Library/LaunchAgents/ai.hermes.gateway.plist | 网关 launchd 服务定义 |